ARCHITECTURE

正文

ARCHTECTURE.md: Keep it short,the shorter it is, the less likely it will be invalidated by some future change. only specify things that are unlikely to frequently change. Don’t try to keep it synchronized with code. Instead, revisit it a couple of times a year. ARCHITECTURE.md 应该写成什么样：它不是实现细节文档，而是整个代码库的导航地图。

先给出“鸟瞰图”

开头要先说明项目整体在解决什么问题：

• 用户是谁；
• 核心业务目标是什么；
• 系统大致如何完成这个目标；
• 最重要的数据流或请求链路是什么。

例如：

用户提交任务
→ API 接收请求
→ 调度模块分配任务
→ Worker 执行
→ 结果写入数据库
→ 前端展示状态

这一层不讨论具体函数、类或算法，而是帮助读者先建立全局心智模型。

Then, specify a more-or-less detailed codemap. ARCHITECTURE.md 应重点描述：

• 核心模块；
• 模块边界；
• 依赖方向；
• 数据或控制流；
• 关键入口。

不要在里面展开：

• 某个类有哪些方法；
• 某个算法如何实现；
• 数据库字段细节；
• 某个函数的异常处理逻辑。

这些内容应放在：

• 单独的设计文档；
• 模块级 README；
• 源码注释；
• 接口文档。

编写 codemap 时，要反过来检查项目结构：

逻辑上相邻的功能，在目录树中是否也相邻？

# Architecture

## Problem Overview

系统解决什么问题，服务哪些用户，以及核心工作流程。

## System Flow

User → API → Service → Repository → Database

## Code Map

### src/api

HTTP 接口层。负责解析请求和返回响应，不包含业务逻辑。

### src/services

业务逻辑层。协调领域规则和数据访问。

### src/repositories

数据访问层。封装数据库和外部存储。

### src/workers

异步任务执行模块。

## Dependency Rules

API → Service → Repository

Repository 不得依赖 Service 或 API。

## Related Documents

- 认证实现：docs/design/auth.md
- 数据模型：docs/generated/schema.md

写名字，而不是写固定链接。

为什么不建议直接链接

例如文档写：

[src/auth/service.ts#L42](...)

这种链接很容易失效，因为：

• 文件可能被移动；
• 行号会变化；
• 分支不同；
• 类或函数被重构；
• 仓库结构发生调整。

相比之下，写：

认证逻辑主要由 AuthService 负责。

即使文件位置变化，读者仍然可以通过符号搜索找到它。

Explicitly call-out architectural invariants architectural invariant 可以理解为：

无论代码如何演化，都必须持续成立的架构规则。

例如：

Controller 只能依赖 Service。
Service 不能依赖 Controller。
Domain 层不能依赖数据库实现。
UI 层不能直接访问数据库。

这些不是某个函数的实现细节，而是整个系统必须遵守的长期约束。

[architecture_example](/en/original-notes/self_study_notes/harness/OpenAI Harness/architecture_example)